home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / tools / czesc_3 / quickhelp / help.doc < prev    next >
Text File  |  1990-12-20  |  20KB  |  479 lines
  1. ==============================================================================
  2.  
  3.         Quick HELP                      V2.0
  4.         © J.Tyberghein                  Mon Nov 12 12:17:09 1990
  5.  
  6. ==============================================================================
  7.  
  8.  
  9.  
  10. Preface
  11. -------
  12.   These programs are intended for everyone. They are extremely useful
  13.   if you are, for example, a programmer and you have some help-files.
  14.  
  15.   Suppose that you want to know the syntax of the EXEC AllocMem command.
  16.   Normally you would start an editor (or use the one which is already in
  17.   memory) and load the corresponding help-file. (You can of course 'type'
  18.   them, but this can be very timeconsuming if the help-file is big)
  19.   Then you must search the right entry in this help-file.
  20.   This may look easy to you, but sometimes it's just difficult enough to
  21.   refrain you from using such help-files.
  22.  
  23.   These three utilites (MakeHelp, Help and ArcFiles) allow you to
  24.   make your own help-files. When this is done you simply type
  25.   'Help AllocMem' and there comes your information !
  26.  
  27.   To guarantee maximum flexibility these programs are able to read files
  28.   crunched with the PowerPacker (Author Nico François).
  29.   You can crunch each help-file individually and then archive them in
  30.   one big file. The advantage of this is that the resulting file will
  31.   be smaller than the sum of the original files (although a bit bigger
  32.   than if you had crunched them all together), but it will only be necessary
  33.   to decrunch the individual files when needed (of course this will be
  34.   done automatically for you).
  35.   To guarantee an even greater amount of flexibility you can show the
  36.   information you want in every editor you like. (The ouput will be
  37.   put in a temporary file and the editor will automatically be
  38.   invoked with this file)
  39.   And in case you have PPMore (also by Nico François), the biggest
  40.   amount of flexibility is likely to be yours. For in that case there
  41.   is no additional overhead for using a temporary file.
  42.  
  43.   These programs (Help, MakeHelp and ArcFiles V2.0) are public domain but
  44.   contributions and some utilities are always welcome.
  45.   If you want to use any of these programs for commercial purposes please
  46.   write for permission !
  47.  
  48.   If you have any suggestions or remarks you can write to (Bug reports are
  49.   welcome too)
  50.  
  51.                             Jorrit  Tyberghein
  52.                              Hepmansbossen 31
  53.                            2450 Meerhout BELGIUM
  54.  
  55.  
  56.  
  57.   NOTE:
  58.     If you want to use QuickHelp you must have AmigaDOS 2.0 (or later :-).
  59.     If you want to use the MEMORY option with PPMore (explained later) you
  60.     need PPMore version 2.0 or later.
  61.     These programs accept crunched DATA-files made by PowerPacker 1.1 or
  62.     later.
  63.     Only use Help, MakeHelp and ArcFiles if they have the same
  64.     version number (unless stated otherwise).
  65.     If you use the PROG option (in HELP), you must assign T:.
  66.     All this utilities are pure, so you can use them with 'Resident'.
  67.     MakeHelp and Help require the powerpacker.library (install by
  68.     double-clicking 'Install_lib').
  69.  
  70.  
  71.   At the end of this document you find a simple example.
  72.  
  73.  
  74. New in QuickHelp V2.0
  75. ---------------------
  76.  
  77.   ARP dependancy is removed
  78.   AmigaDOS 2.0
  79.   Made pure
  80.   New LIST option in Help
  81.   ArcFiles can extract files
  82.  
  83.  
  84. ArcFiles
  85. --------
  86.  
  87.   +---------------------------------------------------------------+
  88.   | Commandline template:                                         |
  89.   |   Files/m,TO=ARC/a,ADD/s,LIST/s,X=EXTRACT/s,FP=FULLPATH/s:    |
  90.   |---------------------------------------------------------------|
  91.   | Usage:                                                        |
  92.   |   ArcFiles { <Files>... } <TO Dest> [ADD|EXTRACT] [FULLPATH]  |
  93.   | or                                                            |
  94.   |   ArcFiles <ARC Archive> LIST                                 |
  95.   +---------------------------------------------------------------+
  96.  
  97.   This program is a small archiver. It is made especially for the
  98.   help utilities. You can use it for your own purposes if you like
  99.   (but not commercially).
  100.  
  101.     <Files>      : files to archive
  102.                    you can use all AmigaDOS wildcards
  103.                    (see the DOS documentation for more information)
  104.     <Dest>       : this is the destination for the archive
  105.     ADD          : if this option is used the <Files> will be appended
  106.                    to an existing archive <Dest>
  107.     LIST         : generate a listing of this archive
  108.                    if this option is specified <Dest> must be an
  109.                    existing archive file
  110.     EXTRACT      : extract all files matching the <Files> patterns
  111.     FULLPATH     : use this option if you want to extract the
  112.                    archive files in their directory, otherwise
  113.                    they will be extracted in the current directory
  114.  
  115.   examples:
  116.  
  117.     ArcFiles dh0:docs/#?.docs to dh0:DocArc.ppa
  118.       will archive all files in 'dh0:docs' with extension '.docs' in the file
  119.       'dh0:DocArc.ppa'. If this destination file was there already it
  120.       will be deleted.
  121.  
  122.     ArcFiles dh0:docs/#?.docs to dh0:DocArc.ppa add
  123.       will add the files in 'dh0:docs' with extension '.docs' to the
  124.       existing archive file dh0:DocArc.ppa
  125.  
  126.     ArcFiles arc dh0:DocArc.ppa list
  127.       will generate a listing of all the files in 'dh0:DocArc.ppa'.
  128.  
  129.     ArcFiles dh0:docs/Exec.doc df0:sources/#?.c to df0:ExecAndSources.ppa
  130.       will archive the file 'dh0:docs/Exec.doc' and all files in
  131.       'df0:sources' with extension '.c' in 'df0:ExecAndSources.ppa'.
  132.       Note that ArcFiles will give no warning if 'dh0:docs/Exec.doc'
  133.       does not exist. It will simply not archive it (rather obvious
  134.       isn't it ?).
  135.  
  136.     ArcFiles a#? b#? arc Archive extract fp
  137.       Extract all files from 'Archive' that start with an 'a' or a 'b'.
  138.       Use the original path name for these files.
  139.  
  140.   Arc format (V1.2, format has not changed since V1.2):
  141.  
  142.     I will give a description of the Arc format, so you can use it for
  143.     your own purposes.
  144.  
  145.     The file starts with two longwords. The first is equal to 'PPA1'.
  146.     The second is the offset in the file to where the Archive descriptor
  147.     table is located.
  148.     After these two longwords the files begin.
  149.     The archive descriptor (at the end of the file) contains the following:
  150.       A null terminated string  : the name and path name of the sub-file
  151.       A long word indicating the offset of the sub-file in this archive
  152.       A long word indicating the length of the sub-file
  153.     And this is repeated for every sub-file in the archive.
  154.     Simply check for EOF to stop scanning.
  155.  
  156.  
  157. MakeHelp
  158. --------
  159.  
  160.   +---------------------------------------------+
  161.   | Commandline template:                       |
  162.   |   From,CtrlFile,ADD/s,WORD/n,CLASS/k:       |
  163.   |---------------------------------------------|
  164.   | Usage:                                      |
  165.   |   MakeHelp <Help file> <Ctrl file> [ADD]    |
  166.   |            [WORD num] [CLASS class]         |
  167.   +---------------------------------------------+
  168.  
  169.   This program makes the help control files for you. These control
  170.   files are plain ASCII so you can add or delete lines as you wish.
  171.  
  172.     <Help file>   : the file containing the help (in a special format,
  173.                     explained below)
  174.     <Ctrl file>   : the control file to make or to adjust
  175.     ADD           : specify this option if you want to add help items
  176.                     to the control file (adjusting)
  177.     WORD num      : normally the parser searches for the first word in
  178.                     the text. This word will be the keyword for you to
  179.                     use with the help utility (see below for an example).
  180.                     With this option you can specify which word you want
  181.                     as the keyword
  182.     CLASS class   : to make the Quick Help utilities more flexible, you
  183.                     can group your help items in classes. When you use
  184.                     this option the newly added help items will be of
  185.                     class <class>. If you omit this option they will have
  186.                     class 'Misc' (from miscellaneous).
  187.  
  188.   The help-file must have the following format:
  189.  
  190.     If the help-file is a crunched or normal file:
  191.  
  192.       When you place a marker ('@') in the beginning of a line, MakeHelp
  193.       will search for the next (depending on the WORD option) word and
  194.       will start a new help item entry here. This word is then the keyword
  195.       for the Help utility.
  196.       This marker is not necessary in the beginning of the file.
  197.       At the end of the help text for this item you place '===' in the
  198.       beginning of the line. This is not necessary at the end of the file.
  199.  
  200.     If the help-file is an archive (each individual file may
  201.     be crunched):
  202.  
  203.       If each individual file in the help-file corresponds with one help
  204.       item, you need not place markers. The items are selected automatically.
  205.       In fact you can think about each individual file as a real file.
  206.       With this in your mind you can reread the previous paragraph.
  207.       If there are multiple help items in each individual file you must
  208.       place the corresponding markers (read the previous paragraph for
  209.       for more information)
  210.  
  211.   examples:
  212.  
  213.     MakeHelp dh0:docs/exec.ppa s:help.file
  214.       will make a new file 's:help.file' and add all marked help items in
  215.       the archive file 'dh0:docs/exec.ppa'. If every individual file in
  216.       the archive corresponds with one help-item, no markers are needed.
  217.  
  218.     MakeHelp dh0:docs/arexx.doc s:help.file add
  219.       will add all marked help items in the normal file 'dh0:docs/arexx.doc'
  220.       to 's:help.file'. The file 's:help.file' must already exist.
  221.  
  222.     MakeHelp dh0:docs/arexx.doc s:help.file add word 2
  223.       same as previous but we now take the second word after the marker '@'
  224.       as our keyword.
  225.  
  226.     MakeHelp dh0:docs/exec.ppa s:help.file class exec
  227.       same as the first example, but now the items will have class 'exec'
  228.       instead of 'Misc'.
  229.  
  230.   Control file format (V1.2, format has not changed since V1.2):
  231.  
  232.     There are two possible lines in a control file: an option line or
  233.     a normal line.
  234.     - An option line starts with '#'. The following options are supported:
  235.           PROG prog
  236.             When Help selects a help item after this option, the help text
  237.             will be directed to the program 'prog' (most likely an editor).
  238.             While prog is executing you can find the help text in the
  239.             file t:HelpTemp.
  240.           MEMORY prog
  241.             Same as previous option, but now there is no temporary file
  242.             needed. The help text is loaded directly in memory. At the moment
  243.             only PPMore (version 2.0 and later) supports this option (MEMORY
  244.             PPMore), but you can write your own programs to support this option
  245.             if you like. You could, for example, use this option to make an
  246.             efficient ARexx interface.
  247.             When prog is executed it will have the following argument line:
  248.               MEMVIEW <Hex address memory>,<Hex length>,<Hex options>,
  249.               <Title string>
  250.             The first three hex integers are all longwords.
  251.             If the first bit (bit 0) of the last hex integer (Hex options) is
  252.             1, you must free the memory when you are ready (With Help this
  253.             is always the case).
  254.             for example:
  255.               MEMVIEW C02310,12C0,1,Title
  256.               must be interpreted as:
  257.                 on address 0xC02310 you find my text. It is 0x12C0 bytes long
  258.                 and you must free it after you are ready. The title is
  259.                 'Title'.
  260.           RUN
  261.             Use this option if you want to run <prog> (from MEMORY or PROG)
  262.             instead of executing. (executing is the default)
  263.           NORUN
  264.             Use this option if you want to execute <prog>. (default)
  265.           STDO
  266.             When this option is used, the help text will go to the
  267.             standard Output (the CLI window).
  268.             This option overrides PROG and MEMORY and is the default.
  269.           CLASS <class>
  270.             All following help items will be of class <class>.
  271.           FILE <file>
  272.             Default file for help text (explained below).
  273.     - All other lines are help item lines.
  274.         They have the following format:
  275.           <KeyWord> '|' <File> or '*' '|' <Offset> [ '|' <individual file> ]
  276.           <KeyWord> is obvious.
  277.           <File> is the file where the help text can be found.
  278.             If <File> is a '*' the current file is taken (FILE option).
  279.           <Offset> is the offset in the file where the help text starts
  280.             if the file is not archived, and the offset in the individual
  281.             file if the file is archived.
  282.           <individual file> (only for archived files) is the individual
  283.             file where the help text can be found.
  284.         This control file format implies that:
  285.           - If you change the help-file you must change the control file,
  286.             because some offsets could change.
  287.           - If you add individual files to the help-file (an archive file in
  288.             this case) you need not change the offsets because the offsets are
  289.             relative in the individual files, and you only add another
  290.             individual file.
  291.           - If a help-file is not an archive you may freely crunch or
  292.             decrunch this file (with PowerPacker), because the offsets will
  293.             not change
  294.             (the offsets are always the offsets in the decrunched file).
  295.           - Crunched archive files are not supported (and not very useful).
  296.           - If you rename the help-file, you must change the corresponding
  297.             FILE option in the control file.
  298.  
  299.  
  300. Help
  301. ----
  302.  
  303.   +-----------------------------------------------------------------+
  304.   | Commandline template:                                           |
  305.   |   Name/a,CtrlFile,RUN/s,NORUN/s,MEMORY/k,PROG/k,STDO/s,LIST/s:  |
  306.   |-----------------------------------------------------------------|
  307.   | Usage:                                                          |
  308.   |   Help [<Class>,]<Name> [<File>] [RUN | NORUN]                  |
  309.   |        [STDO | (MEMORY | PROG) prog] [LIST]                     |
  310.   +-----------------------------------------------------------------+
  311.  
  312.   This utility gives you the help you want.
  313.  
  314.     <Name>        : this is the help item you want help about
  315.                     You will get the first corresponding help item
  316.                     HELP finds.
  317.                     Note that it is not necessary to give the full
  318.                     help item name. Case is not important either.
  319.                     You can use wildcars in <Name>.
  320.     <Class>       : if <Class> is specified HELP will look for the
  321.                     help item in this Class.
  322.                     Note that it is not necessary to give the full
  323.                     class name. Case is not important.
  324.     <File>        : control file (made by MakeHelp). 's:help.file' is
  325.                     the default.
  326.     RUN NORUN STDO MEMORY PROG RUN
  327.                   : these options are the same as the equivalent options
  328.                     in the control file. When one of these options is
  329.                     given, the corresponding control file options are
  330.                     ignored.
  331.     LIST          : Do not give help, but list all items that correspond
  332.                     with the given <Class> and <Name>.
  333.  
  334.   examples:
  335.  
  336.     Help AllocMem
  337.       gives help about the EXEC function 'AllocMem' (if your help-files and
  338.       control file are correct)
  339.  
  340.     Help NewExec,AllocMem
  341.       will give help about the EXEC function 'AllocMem' in class 'NewExec'.
  342.       (class 'NewExec' could for example contain all additions to the
  343.       'AllocMem' function in 2.0)
  344.  
  345.     Help AllocMem run memory ppmore
  346.       gives help about 'AllocMem'. HELP will run 'PPMore'. Because we used
  347.       the 'memory' option, there will be no temporary file.
  348.       Note that you can only use the 'memory' option if you have PPMore
  349.       1.3 or later.
  350.  
  351.  
  352. Global example
  353. --------------
  354.  
  355.   Suppose that I have 3 help-files, each one containing 2 help items.
  356.  
  357.     Helpfile1:
  358.       | command list
  359.       |    ... (help for list command)
  360.       | command dir
  361.       |    ... (help for dir command)
  362.  
  363.     Helpfile2:
  364.       | command copy
  365.       |    ... (help for copy)
  366.       | move
  367.       |    ... (help for move)
  368.  
  369.     Helpfile3:
  370.       | command delete
  371.       |    ... (help for delete)
  372.       | command format
  373.       |    ... (help for format)
  374.  
  375.   Fine,... I notice that each help item (like 'list','dir','copy',...) is
  376.   the second word, but I didn't realize this wasn't the case with 'move' !
  377.   I must add marks to the help-files because every help-file contains 2
  378.   help items.
  379.  
  380.     Helpfile1:
  381.       | @command list
  382.       |    ... (help for list command)
  383.       | ===
  384.       | @command dir
  385.       |    ... (help for dir command)
  386.       | ===
  387.  
  388.     Helpfile2:
  389.       | @command copy
  390.       |    ... (help for copy)
  391.       | ===
  392.       | @move
  393.       |    ... (help for move)
  394.       | ===
  395.  
  396.     Helpfile3:
  397.       | @command delete
  398.       |    ... (help for delete)
  399.       | ===
  400.       | @command format
  401.       |    ... (help for format)
  402.       | ===
  403.  
  404.   (Strange, I still didn't see that 'move' is not the second word !)
  405.   First I am going to crunch all help-files with the PowerPacker CLI
  406.   command.
  407.   So I type:
  408.  
  409.     1> crunch HelpFile#? ram:
  410.  
  411.   All my help-files are on the ram disk.
  412.  
  413.     1> dir ram:
  414.       |     t (dir)
  415.       |  helpfile1.pp                   helpfile2.pp
  416.       |  helpfile3.pp
  417.  
  418.   Now I archive them.
  419.  
  420.     1> arcfiles ram:#? to ram:HelpFiles.ppa
  421.     1> delete ram:#?.pp
  422.     1> dir ram:
  423.       |     t (dir)
  424.       |  HelpFiles.ppa
  425.  
  426.   Everything is going fine. Let's make a control file.
  427.  
  428.     1> makehelp ram:HelpFiles.ppa s:Help.File word 2 class Commands
  429.  
  430.   I have made 6 help items in class 'Commands'
  431.  
  432.     1> type s:Help.File
  433.       | #FILE ram:HelpFiles.ppa
  434.       | #CLASS Commands
  435.       | delete | * | 1 | ram:helpfile3.pp
  436.       | format | * | 80 | ram:helpfile3.pp
  437.       | list | * | 138 | ram:helpfile1.pp
  438.       | dir | * | 81 | ram:helpfile1.pp
  439.       | copy | * | 125 | ram:helpfile2.pp
  440.       | this | * | 98 | ram:helpfile2.pp
  441.  
  442.   Oops ! Something went wrong ! I didn't need a help-item named 'this' !
  443.   But this is no problem. Simply edit 's:Help.File' and change
  444.   'this' to 'move'.
  445.   So everything is allright. Let's try it.
  446.  
  447.     1> help del
  448.       | command delete
  449.       |    ... (help for delete)
  450.  
  451.   There are still two things I have to do. First I want to put the archive
  452.   'HelpFiles.ppa' on my disk, because it won't live very long on my ram disk.
  453.  
  454.     1> copy ram:HelpFiles.ppa df0:
  455.  
  456.   Now I change the FILE option in 's:Help.File'.
  457.   I add two other lines because I want the help output in the PPMore window.
  458.  
  459.     1> type s:Help.File
  460.       | #FILE df0:HelpFiles.ppa                <<<
  461.       | #MEMORY PPMore                         <<<
  462.       | #RUN                                   <<<
  463.       | #CLASS Commands
  464.       | delete | * | 1 | ram:helpfile3.pp
  465.       | format | * | 80 | ram:helpfile3.pp
  466.       | list | * | 138 | ram:helpfile1.pp
  467.       | dir | * | 81 | ram:helpfile1.pp
  468.       | copy | * | 125 | ram:helpfile2.pp
  469.       | this | * | 98 | ram:helpfile2.pp
  470.  
  471.   Everything is ready !
  472.  
  473.  
  474. ==============================================================================
  475.  
  476.                        End of Quick HELP 2.0 document
  477.  
  478. ==============================================================================
  479.